iA Writer supports a variety of commands to open, create, read, and write files.

Summary

Overview

Commands can be set to iA Writer by constructing special URLs:

ia-writer://command?parameter1=value1&parameter2=value2

x-callback-url

All commands can support x-callback-url:

ia-writer://x-callback-url/command?x-parameter1=x-value1&parameter1=value1&parameter2=value2

Some commands will return parameters on x-success.

Auth

For privacy and security, commands that modify or return data using x-callback-url require auth-token parameter. Auth token is synced across all your devices using iCloud. Auth token can be found in:

Data Types

String
Percent encoded. 4,000 or fewer characters before encoding.
Library Path
Percent encoded.
/File.txt refers to a file in the default location (iCloud or local).
Ideas: File.txt refers to a file in the custom library location named Ideas.
From Other Apps: File.txt is available on iOS.
Use contextual menu in Library and Organizer to copy paths.
Boolean
Either true or false.
Author
Percent encoded. For example: AI or ChatGPT <chat.openai.com>.

Interface Commands

Open a screen in iA Writer.

open command

Opens Editor with an existing document if found, or a new empty document.

Parameters
path
Library Path. Required.
edit
Boolean. Optional. Supported only on iOS and iPadOS. false by default. If true, keyboard will be shown.
new-window
Boolean. Optional. Supported only on macOS. false by default. If true, will open the document in a new window.
Return parameters on x-success

None.

new command

Opens Editor with a new document.

Parameters
path
Library Path. Optional. Path for the file to be created. If omitted the file will be created at the root of the default location. If the path points to a directory, the file will be automatically named. If the path points to a file, it must have a plain text file extension, or the path will be ignored. The proposed filename will be used, but adjusted to avoid overwriting an existing file.
text
String. Optional. File contents.
edit
Boolean. Optional. Supported only on iOS and iPadOS. false by default. If true, keyboard will be shown.
new-window
Boolean. Optional. Supported only on macOS. false by default. If true, will open the document in a new window.
author
Author. Optional.
Return parameters on x-success

None.

Opens Quick Search with a given query.

Parameters
query
String. Optional.

Return parameters on x-success

None.

Data Commands

Silenty read and write data.

read command

Reads and returns files contents.

Parameters
auth-token
String. Required.
path
Library Path. Required. Path to the file to read.

Return parameters on x-success

path
Library Path. Path to the file.
text
String. File text.

write command

Creates or modifies an existing file and returns file contents.

Parameters
auth-token
String. Required.
path
Library Path. Required.
text
String. Optional.
mode
String. Optional.
create Default. Adjusts last path component to avoid replacing an existing file.
replace Replaces an existing file.
add Add the given text to an existing file; creates a file if it doesn’t exist.
patch Detects differences between the and file contents and text, and attributes edits to author, if provided.
add-location
String. Optional. Used only when mode is append.
beginning Add text at the beginning of a file.
end Default. Add text at the end of a file.
add-padding
String. Optional. Used only when mode is append.
sentence Add text as a sentence.
line Default. Add text as a line.
paragraph Default. Add text as a paragraph.
author
Author. Optional.

Return parameters on x-success

path
Library Path. Path to the file that was created or modified.
text
String. File contents after writing.

version command

Returns iA Writer app version and URL scheme version.

Parameters

None.

Return parameters on x-success

scheme-version
String. URL scheme version.
app-version
String. App version.

Version History

1
Initial release.
2
Fixed write command parameter append-padding. It was inverted in version 1: padding was appended with false, and not appended with true.
3
Changed write command with mode=append to create a file if it doesn’t exist.
4
Added open and new command parameter new-window.
Changed open command to open a new empty file if file at path is not found.
Changed write command to create target folder if it doesn’t exist.
Renamed Path data type to Library Path, and updated the data type format. Old format is deprecated.
5
Added author parameter support to write command.
6
Added author parameter support to new command.
Adjusted write command with mode=append
Renamed mode=append to mode=add, append-location to add-location and append-padding to add-padding.
Added support for add-padding values sentence and line. paragraph remains default.
Added write command mode=patch.
Adjusted read command to avoid returning authorship.